feat(select): allow HTML within options by thetaPC · Pull Request #31072 · ionic-team/ionic-framework

thetaPC · 2026-04-09T16:35:40Z

Issue number: resolves #29890

What is the current behavior?

Select only allows plain text to be passed within it's options.

What is the new behavior?

ion-select-option

Added default slot support for custom HTML content (images, avatars, icons, etc.) when innerHTMLTemplatesEnabled is true
Added start and end named slots for content that appears in the overlay interface but not in the selected text
Added description prop for text rendered below the option label in the overlay

ion-select

Selected text renders HTML content from the default slot, excluding start/end slot content
aria-label derives plain text only from the default slot, ensuring screen readers don't read slotted or element content
Added CSS variables for styling media within the selected text (--select-text-media-width, --select-text-media-height, etc.)

Overlay interfaces (alert, action-sheet, select-popover, select-modal)

All four interfaces render rich content (start, end, description, HTML label) consistently via the shared renderOptionLabel utility
Public interfaces (ActionSheetButton, AlertInput, SelectPopoverOption, SelectModalOption) are unchanged — rich content fields are on internal extended interfaces (SelectActionSheetButton, SelectAlertInput, SelectOverlayOption)
Content is sanitized via sanitizeDOMString before DOM injection to prevent XSS

Utilities

Added select-option-render.tsx: shared render utility for option labels across all overlay components
Added getOptionContent: extracts and clones slot content from ion-select-option for overlays and selected text
Added getDefaultSlotPlainText — extracts plain text from the default slot, used for labels and aria

Tests

Added E2E tests for rich content rendering across all four interfaces (single and multiple selection)
Added tests for slot positioning (start/end placement verification)
Added tests for selected text content verification (excludes slotted content)

Does this introduce a breaking change?

Yes
No

No, developers will be able to continue using plain text for select options as usual.

Other information

Preview

vercel · 2026-04-09T16:36:22Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Apr 15, 2026 11:20pm

…7137

thetaPC · 2026-04-10T18:16:06Z

+// --------------------------------------------------
+
+.action-sheet-button-label {
+  gap: 12px;


I decided to use the same value that ionic uses.

thetaPC · 2026-04-10T18:17:21Z

-            <div class="alert-button-inner">
-              <div class="alert-checkbox-icon">
-                <div class="alert-checkbox-inner"></div>
+        {inputs.map((i) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:24Z

-            <div class="alert-button-inner">
-              <div class="alert-radio-icon">
-                <div class="alert-radio-inner"></div>
+        {inputs.map((i) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:38Z

-                   */
-                  this.closeModal();
-                }
+        {this.options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:46Z

-          onIonChange={(ev) => {
-            this.setChecked(ev);
-            this.callOptionHandler(ev);
+    return this.options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:19:05Z

+  /**
+   * Text that is placed underneath the option text to provide additional details about the option.
+   */
+  @Prop() description?: string;


Description isn't being used here to display on the screen because ion-select-option isn't used to display the options, it's done through the respective interface. So description is passed to the interface.

thetaPC · 2026-04-10T18:20:34Z

+        <slot name="start"></slot>
+        <slot></slot>
+        <slot name="end"></slot>


Slots aren't being used here to display on the screen because ion-select-option isn't used to display the options, it's done through the respective interface. So slots are passed to the interface and the rendering is done with a new utility.

Even though it's not used to display here, it's still useful to include here so the docs can generate that "slots" are available for the options.

thetaPC · 2026-04-10T18:21:40Z

-          onIonChange={(ev) => {
-            this.setChecked(ev);
-            this.callOptionHandler(ev);
+    return options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:21:47Z

-                   */
-                  this.dismissParentPopover();
-                }
+        {options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

ShaneK

This is looking really good! Just some feedback on some things I noticed

ShaneK · 2026-04-13T18:39:12Z


 export interface ActionSheetButton<T = any> {
-  text?: string;
+  text?: string | HTMLElement;


Widening text from string to string | HTMLElement here affects all action-sheet consumers, not just select-driven ones. Same with AlertInput.label. Anyone calling actionSheetController.create() who does button.text.toLowerCase() or passes text to a string-typed function will get TS errors. Since this targets next, breaking changes are expected, but would it be cleaner to add a separate property (e.g., richText or contentElement) for the HTMLElement case? That way existing string usage stays untouched.

Great point! cc0af05 and 49e0e6c

ShaneK · 2026-04-13T18:41:29Z

          <span class="action-sheet-button-inner">
            {b.icon && <ion-icon icon={b.icon} aria-hidden="true" lazy={false} class="action-sheet-icon" />}
-            {b.text}
+            {renderOptionLabel(optionLabelOptions, 'action-sheet-button-label')}


This changes the DOM structure for all action-sheet buttons, not just ones created through select. Previously {b.text} rendered directly inside .action-sheet-button-inner, now it's wrapped in <span class="action-sheet-button-label"><span>...</span></span>. Same thing happens in alert for radio/checkbox labels. Any app CSS targeting these internal elements will break. Should renderOptionLabel only wrap when rich content is actually present (when startContent/endContent/description exist), falling back to the original rendering for plain strings?

I do understand that breaking changes are acceptable here and this may be intended. Just double checking that's what you're going for.

There's no need for the extra wrappers so it's now back to plain: 0c7e4d6 and 17e9e37

ShaneK · 2026-04-13T18:43:45Z

+
+          // Clear previous content and clone new nodes
+          el.innerHTML = '';
+          Array.from(content.childNodes).forEach((n) => el.appendChild(n.cloneNode(true)));


The select's closed-state display goes through sanitizeDOMString before innerHTML injection, but this overlay path clones nodes with cloneNode(true) without sanitization. Inline event handlers (onclick, onerror) on elements inside ion-select-option get faithfully cloned into the overlay DOM. The two rendering paths for the same content have different security postures.

ShaneK · 2026-04-13T18:45:59Z

+          <script>
+            window.Ionic = {
+              config: {
+                innerHTMLTemplatesEnabled: true,


This window.Ionic = { config: { innerHTMLTemplatesEnabled: true } } replaces the entire config object that setContent already sets in the head (which includes mode and theme). I think it works by accident because md is the fallback on non-iOS platforms, but you're losing the explicit config. Should be merging instead: window.Ionic = window.Ionic || {}; window.Ionic.config = { ...window.Ionic.config, innerHTMLTemplatesEnabled: true };

I moved them to their own page: 8a4e59b

ShaneK · 2026-04-13T18:48:13Z

        },
+        startContent: startContent ?? undefined,
+        endContent: endContent ?? undefined,
+        description: option.description,


You're gating startContent/endContent behind this.customHTMLEnabled but description gets passed through regardless. Is that intentional? If someone has innerHTMLTemplatesEnabled set to false (the default), they'd still see descriptions in overlays but not the slot content. Feels like it should be consistent either way.

It was intentional. Devs can only pass string text as a description. To me, it would feel weird that a dev would have to enable innerHTMLTemplatesEnabled when they only want to have a description (no start or end slots). It follows how other props are being handled.

ShaneK · 2026-04-13T18:50:28Z

+ * spacing between the items without changing the display to prevent
+ * losing the ellipsis behavior.
+ */
+.select-text > * {


.select-text > * applies margin-inline-start to the first child too, which adds unwanted leading space. Should be .select-text > * + * or .select-text > *:not(:first-child) to only space between items. Same thing in the ionic theme file.

I ended up finding an issue with my approach and the proposed approached when it came to multiple values and the rich content option is second on the list. The styling isn't applied as intended so there's no spacing between the plain text and the rich content. I ended wrapping everyone in a span if it has rich content and if it's in the select text: f2695ca

ShaneK · 2026-04-13T18:52:43Z

+// Ionic Select Popover
+// --------------------------------------------------
+
+// Select Modal: Select Option


This says "Select Modal" but it's the select-popover file.

ShaneK · 2026-04-13T18:54:58Z

+    <script>
+      window.Ionic = {
+        config: {
+          innerHTMLTemplatesEnabled: true,


Setting innerHTMLTemplatesEnabled: true globally here means all existing tests that navigate to this page now run with a different config than they were written for. Could the existing overlay open/dismiss and focus tests be affected? Would it be safer to create a separate test page for the rich content tests, or set the config per-test in page.setContent?

Moved it to their own page: 8a4e59b

thetaPC · 2026-04-15T23:26:04Z

+// --------------------------------------------------
+
+.action-sheet-button-label {
+  gap: 12px;


Based it off ionic theme

feat(select): allow HTML within options

9918f4a

github-actions bot added the package: core @ionic/core package label Apr 9, 2026

feat(select): add HTML to options

d0a8a56

github-actions bot added package: angular @ionic/angular package package: vue @ionic/vue package labels Apr 10, 2026

vercel bot deployed to Preview April 10, 2026 03:46 View deployment

refactor(many): rename files to common

d53d627

vercel bot deployed to Preview April 10, 2026 03:48 View deployment

chore(select): run build

5415cad

vercel bot deployed to Preview April 10, 2026 03:52 View deployment

thetaPC added 2 commits April 9, 2026 21:11

refactor(select): cleanup

8f3e623

Merge branch 'next' of github.com:ionic-team/ionic-framework into FW-…

f0b45d3

…7137

vercel bot deployed to Preview April 10, 2026 04:14 View deployment

chore(): run build proper

a48cf66

vercel bot deployed to Preview April 10, 2026 04:19 View deployment

thetaPC commented Apr 10, 2026

View reviewed changes

refactor(select): cleanup and tests

e9eb575

vercel bot deployed to Preview April 10, 2026 22:59 View deployment

refactor(select): select text spacing

e4bce6b

vercel bot deployed to Preview April 10, 2026 23:35 View deployment

fix(select): revert deletion

03b8351

vercel bot deployed to Preview April 11, 2026 00:59 View deployment

thetaPC marked this pull request as ready for review April 11, 2026 02:06

thetaPC requested a review from a team as a code owner April 11, 2026 02:06

thetaPC requested review from BenOsodrac and ShaneK and removed request for BenOsodrac April 11, 2026 02:06

ShaneK requested changes Apr 13, 2026

View reviewed changes

refactor(many): add internal type

cc0af05

vercel bot deployed to Preview April 14, 2026 17:08 View deployment

refactor(select): split out type

49e0e6c

vercel bot deployed to Preview April 14, 2026 17:18 View deployment

refactr(select): return string label as is

0c7e4d6

vercel bot deployed to Preview April 14, 2026 18:03 View deployment

thetaPC added 2 commits April 14, 2026 11:30

feat(select): add useSpan boolean

17e9e37

docs(select-popover): fix text

6ef2355

vercel bot deployed to Preview April 14, 2026 18:34 View deployment

fix(select): sanitize content

22dace3

vercel bot deployed to Preview April 14, 2026 21:23 View deployment

feat(select): add spans to rich content select text

f2695ca

vercel bot deployed to Preview April 15, 2026 13:56 View deployment

test(select): add rich content page

8a4e59b

vercel bot deployed to Preview April 15, 2026 20:14 View deployment

feat(select): strip out elements for plain options

deaafb9

vercel bot deployed to Preview April 15, 2026 23:20 View deployment

thetaPC commented Apr 15, 2026

View reviewed changes

thetaPC requested a review from ShaneK April 16, 2026 01:06

Conversation

thetaPC commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

vercel bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thetaPC Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thetaPC Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thetaPC commented Apr 9, 2026 •

edited

Loading

vercel bot commented Apr 9, 2026 •

edited

Loading

thetaPC Apr 10, 2026 •

edited

Loading

thetaPC Apr 14, 2026 •

edited

Loading